Run Handlers

All Mac OS applications can respond to the Run command, even if they aren't scriptable. The Finder sends a Run command to an application whenever one of the following actions occurs while that application is not already running:

The user double-clicks the application's icon.
The user selects the application's icon and chooses Open from the File menu.
The application's icon is in the Apple Menu Items folder and the user chooses it from the Apple menu.
The application's icon is in the Startup Items folder and the user restarts the computer.

If the application is already running when one of these actions occurs, the application is activated but no commands are sent to it. If the application isn't running, the Finder launches the application and sends it a Run command. The application responds by performing the actions the user expects when the application first opens, such as opening an untitled document.

Like any other application, a script application, described in Script Applications, receives a Run command whenever one of the actions just listed occurs. You can provide a handler for the Run command in one of two ways. An implicit Run handler consists of all statements at the top level of a script except for property declarations, script object definitions, and other command handlers. An explicit Run handler is enclosed within an on...end or an on run...end statement, like other handlers.

For example, the script that follows consists of a property declaration, an increment command, a Tell statement, and a handler for the increment command. For the Tell statement to work, you must have an AppleWorks document named Count Log open before you run the script. Each time you run the script, the value of the property x increases by 1 and the increase is recorded in the Count Log file (by replacing the first paragraph with the count).



 
property x : 0



increment() 



tell document "Count Log" of application "AppleWorks"

    select first paragraph of text body

    set selection to "Count is now " & x & "."

end tell



on increment()

    set x to x + 1

    display dialog "Count is now " & x & "."

end increment

The implicit Run handler for this script consists of the statement increment() and the Tell statement--that is, the statements outside the handler, but not including property declarations. If you store this script in a script application and then double-click the script application's icon, the Finder sends a Run command to the script, and the Run command invokes the two statements in the implicit Run handler.

If you rewrite the previous script to use an explicit Run handler, it provides the exact same behavior:



 
property x : 0



on run

    increment()

    tell document "Count Log" of application "AppleWorks"

        select first paragraph of text body

        set selection to "Count is now " & x & "."

    end tell

end run



on increment()

    set x to x + 1

    display dialog "Count is now " & x & "."

end increment

A script can't include both an implicit and an explicit Run handler. If a script includes both an explicit on run handler and top level commands that constitute an implicit Run handler, AppleScript returns an error when you try to compile the script--that is, when you try to run it, check its syntax, or save it.

The Run handlers in the preceding examples respond the same way to a Run command whether the script is saved as a script application or as a compiled script. If the script is saved as a compiled script, you can invoke its Run handler by clicking the Run button in the Script Editor.

You can also send a Run command to a script application from within another script. For information about how to do this, see Calling a Script Application From a Script.